<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
	<head>
		<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
		<title>M3Gen :: Quickstart</title>
		<link rel="stylesheet" href="3gen.docs.css" type="text/css" />		
	</head>
	<body>
		<h1>M3Gen :: Quickstart</h1>			
		<p>
			<i>M3Gen</i> can generate a jsTree model (or some other result model) by executing a <i>m3gen.generateTreeInstanceModel</i> instance with a <i>modelsObj</i> consisting of a 
			<i>generatorModel</i> and an <i>instanceModel</i>.
						
			The <i>instanceModel</i> must be a valid json structure. The parseModel defines rules for how to parse the instanceModel and transform it to the final model.
			The <i>generatorModel</i> contains a <i>ruleSetConfiguration</i> (ruleSets for parsing different types of json objects) and an <i>openList</i> containing ids of jsTree nodes to create in 'open' state.
			The modelsObj can also contain an optional <i>name</i>, which is currently only used for logging purposes.
			
			An example of a ruleSetConfiguration can be found in <i>rulesets/m3gen.ruleSet.person.js</i>
						
			To get notifications of events that occur during the model generation process, eventhandlers can be assigned. 
			The level and type of evenhandling can be tuned at a detailed level (see <a href="eventhandling.html">eventhandling</a>).			
		</p>
		<h2>Quickstart example</h2>
		<p>
			First a list of tree nodes that are currently (or are to be displayed as) open is defined. These should match the jsTree node ids
			which M3Gen generates. Here it is assumed that M3Gen generates ids for persons in the form: objType + '_' + name.first + '_' + name.last.
			<code>
				// openList defines the ids of objects that are to be showed in open state
				var openTreeNodeList_person = ['person_Jack_Johnson'];
			</code>
		</p>
		<p>
			Next a generator model is defined, containing a <i>ruleSetConfiguration</i> (required) and optionally an <i>openList</i> and <i>name</i>.
			<code>
				// configure model used to parse the instance model and generate the resulting jsTree model 
				var generatorModel = { 
					name: 'Person model', 
					ruleSetConfiguration: ruleSetConfiguration_person, 
					openList: openTreeNodeList_person
				}
			</code>
			The <a href="ruleSetConfiguration.html">ruleSetConfiguration</a> must follow a specific structure/syntax, with a <i>ruleSet</i> for 
			each <i>objType</i> encountered during the parsing process.			
		</p>		
		<p>
			Now we can create the full model to pass to the generator. 
			(for an example of a personsModel, see models/person/m3gen.simplePersonModel.js)
			<code>
				// create the full model
				var fullModel_Person = {
				    instanceModel: personModel,
					generatorModel: generatorModel
				};			
			</code>
		</p>
		<p>
			We can now also choose to configure eventhandling (see <a href="configuration.html">configuration</a>).
			Here a setting is supplied saying we want info level for events in the 'parser' and 'branch' phases and a level of 'error' in the others.
			<code>
				m3gen.eventController.settings = m3gen.eventSettings.parserAndBranchOnly; 
			</code>
		</p>		
		<p>
			Finally we execute M3Gen with the full model to create the jsTree model.
			<code>
				// generate the jsTree model
				var m3generator = new m3gen.JsTreeModelGenerator(fullModel_Person);
				var treeData = m3generator.execute();
			</code>
		</p>					
		<p>
			Alternatively we can use the following approach:
			<code>
				// generate the jsTree model
				var m3generator = new m3gen.JsTreeModelGenerator(generatorModel);
				var treeData = m3generator.execute(instanceModel);
			</code>
		</p>			
		<p>
			TODO:
			<ul>
				<li>How to integrate into the jsTree oncallback handlers</li>
				<li>How to use xml2json</li>
				<li>How to use json Schema on ruleSetConfiguration/instanceModel</li>
				<li>Using M3Gen serverside (fx via Jaxer)</li>
			</ul>
		</p>
	</body>
</html>
